Txt2Site User Manual
File types
This page describes the file types you encounter when working with Txt2Site.
Txt2Site needs to know the location of the content directory, the template directory, the include directory and the target directory. It gets these from the config file.
You specify these directories by setting values to the system variables content_dir, template_dir, include_dir and target_dir. Defaults for these variables are:
In the config file the user can also define his own site variables. These variables can be used on a page. Site variables are defined for the whole site. Examples are: site_version, site_name, footer_string, ...
In general variables are given a value by typing variable=string (no space before =).
Lines in the config file beginning with a # are skipped.
As an example view the config file of this site here.
Content files are text files in the content directory defining the content of a page.
Depending on the name there are two types of contentfiles: content files with name default and others.
To view the contentfile of each page use the link at the bottom of the page.
Subdirectories of the content directory are used to define the page structure of your site.
Each subdirectory in the content directory containing a file called default defines a page on the website. Choose the name of the subdirectory carefully because this is used as the name of the page in navigation menus.
If you define a subdirectory without a default file then no page is created for this subdirectory. You only will notice the name of the subdirectory in the generated navigation menus.
The default file behaves like other files in the content directory. See the next section.
Every other file in the content directory (not named default) defines a page on the website. Txt2Site generates this page for you. Choose the name of the file carefully because this is used as the name of the page in navigation menus.
You can put a prefix before the name of a content file or content directory. The effect of the prefix is that the order of menu items is changed according to these prefixes. The prefixes are not visible on the site. Prefixes for sorting have a fixed length and format: 999_
As an example, the content directory structure of this application looks like this (files are red):
content
default
001_Introduction (NL)
default
002_Introduction (EN)
default
003_Quickstart
default
004_User Manual
101_Installation
102_System Overview
103_File Types
104_System Variables
105_System Functions
005_Tutorial
default
006_Markup
201_Txt2Tags
202_Creole
011_Examples
default
013_Examples
default
015_Download
default
Prefixes are optional and need not be unique. Next to sorting menu items, they can be used to exclude items from the menu. See the system functions html_mainmenu_div and html_pagemenu_div.
Txt2Site allows you to use symbolic links for content directories and content files. They behave exactly in the same manner as normal directories and files. So you can reuse content data without copying.
The text of a content file can be divided in two parts:
Page variables are defined in the first section of the content file. Variables are defined by specifying variable_name=value (no spaces around equal sign!).
The first section ends where the first content section begins. A content section begins after a line beginning with <<<<< and ending with >>>>>.
Lines in the first section with variable definitions are only read by Txt2Site if they contain exactly one equal sign. So empty lines or comments are skipped. Although the variable section is optional, it is useful to specify important page variables.
A typical example of a variable section looks like this:
page_format=txt2tags page_template=template page_title=Demo Application page_description=Demo Application for Txt2Site page_header1=Demo Application page_header2=from Text to Site page_keywords=keyword1, keyword2, keyword3 <<<<< content section 1 >>>>>
We use two types of variables
Predefined system variables here are page_format, page_template and page_title. Predefined variables are recognized by the system. Some predefined variables are set by the system and some are set by the user (taking a default value if not set).
For example the variable page_source_mtime (mutation date of content file) is a read-only variable set by the system and can be displayed by the user.
Page_title is a system variable and takes the name of the content file if not specified by the user. See the chapter System Variables for a list of predefined system variables.
The other variables in the example are user defined variables. They are defined and given a value by the user. These variables are displayed on a page by specifying the command ${variable_name} in the HTML template.
Immediately after the variable section comes the content part. It specifies the content of the page. The content part has one or more content sections.
Each content section begins with a line beginning with <<<<< and ending with >>>>>. For readability you can insert comment between the delimiters.
You can insert content sections on different locations on a page by calling the function html_content_div in the template file. See the description of the system function html_content_div.
There are multiple options how Txt2Site interpretes the text of the content part. The page_format variable lets Txt2Site know how to translate the text of each content section to XHTML. If the format is not indicated, the text is default interpreted as Txt2Tags syntax. See chapter System Variables which values the variable page_format can take.
A content section with format Txt2Tags has three areas.
Files in the template directory are used when creating the website. The path of the template directory is specified in the configuration file.
Template files are the HTML framework for your website. Each page has its own template. Variables and functions you put in your template determine where the content, title, navigation menus and other elements go.
The name template is just the default filename. You can change the name of this file through the page parameter page_template. You can use more than one template in your website.
You can put system variables in the template file by typing ${variable} and put system functions by typing $(function).
See the chapter System Variables and the chapter System Functions which variables and functions are available for your template.
As an example view the template file of this site here.
Reusable files are also put in the template directory. Reusable files are files that can be inserted by the function include_file.
Tip: an approved method for easily positioning div-blocks is to use the 960 grid system in your template.
Files in the include directory are used when viewing the website. When Txt2Site generates a website, at the end it copies the include directory to the site/target directory. The path of the include directory is specified in the configuration file.
Examples of files that go in the include directory are stylesheets, images, javascript, ... You can choose freely your subdirectory structure. It is usual to choose separate directories for stylesheets, images and javascript. Using the system variable path_to_root you can reference stylesheets, images and javascript.
The variable path_to_root is the relative path of the current page to the root directory of the website. For example you can reference to a stylesheet with:
href="${path_to_root}include/css/style.css"
Using relative paths with path_to_root makes the website independent of the location. So you can move the root of the website without any adjustments.
Any designer who has worked with large stylesheets will agree that its major weakness is its inability to use variables. Stylesheet variables are one of the top features web developers are asking for in web development.
Txt2Site allows web developers to define variables that are reusable as property values anywhere in a stylesheet.
If a value is often used in a stylesheet - a common example is the value of the color properties - it would be nice modifying just one variable instead of modifying all style rules applying the property/value pair.
To let Txt2Site know where to find stylesheets, a global system variable style_dir is defined.
The value of style_dir must be defined in the config file. It defines a subdirectory of the include directory.
Where are variables for stylesheets defined? Well, because they are global and not page dependant, they must be defined in the config file.
Stylesheet variables can be called in a stylesheet as usual by ${var_name}.
Evaluation of stylesheets (replacing variables) is performed if style_dir is a valid subdirectory of the include directory. Txt2Site evaluates all the stylesheets in the style_dir if it has a .css extension. Evaluation of stylesheets is done immediately after copying the include directory to the target directory. Stylesheets in the target directory are updated where variables are replaced by their value.
If style_dir is not defined or is empty, no evaluation of stylesheets is performed. If you don't use stylesheet variables, make style_dir empty for better performance.
How does it work?
Suppose the config file contains these lines of code:
include_dir=include
style_dir=include/css
body_bg_color=#983221
body_width=860
font_family=Verdana, Arial, Comic Sans MS
Suppose a stylesheet in the include/css directory has these lines of code:
body {
background-color: ${body_bg_color};
width: ${body_width}px;
font-family: ${font_family};
}
Then after evaluation the stylesheet in the target directory has the code:
body {
background-color: #983221;
width: 860px;
font-family: Verdana, Arial, Comic Sans MS;
}
Simple arithmetic can be performed with the bash syntax $((expression)) or $[expression].
For example:
width: $(( ${body_width} + 110 ))px;
or
width: $[ ${body_width} + 110 ]px;
results after evaluating in:
width: 970px;
If you let evaluate a stylesheet, you can also use the function include_file. So you can use reusable parts of a stylesheet if you think this makes life easier.
Target files resides in the target directory. The path of the target directory is specified in the configuration file.
When Txt2Site generates a website, it puts the HTML pages in the target directory. Files outside the target directory are only read and not affected by Txt2Site.
The target directory consists of the generated webpages in its hierarchical order and a copy of the include directory.